[OSDOCS#18748]: CQA support book for 4.20 - #118938
Conversation
openshift-ci
Bot
added
the
size/XXL
rh-sgehlot
changed the title
75aa7fe to
5a50bc5
Compare
|
🤖 Tue Sep 01 15:34:53 - Prow CI generated the docs preview: |
d9bdea3 to
3abdc93
Compare
ba20103 to
483cbbf
Compare
rh-sgehlot
changed the title
stevsmit
added
the
merge-review-in-progress
stevsmit
left a comment
stevsmit
left a comment
There was a problem hiding this comment.
This PR is challenging because of the size and the fact that it seemingly incorporates work from other PRs that were done after https://github.com/openshift/openshift-docs/pull/106162/changes. I've done my best here, but a lot of comments can be ignored. At some point, I gave up nitpicking everything for a 1:1 match (which wasn't possible) in favor of looking for more egregious errors that could cause conflicts in the future (unlikely at this point given that we're so close to AEM migration).
My main concerns are that many of the introductions here do not match what is currently in main/4.21+, so I'm not sure where they came from. I am freshly rebased so I'm fairly certainly my branch is up to date. Here's what you should probably do when revising this PR:
- For the examples of abstracts not match, I would make sure that what is in this PR is what you actually want. I'm not saying that abstracts in this version and in 4.21+ have to match, but I would have thought that was the intention. If you want them to match, double check what I've called out.
- Spot check the comments that I've made throughout the PR. Some can likely be ignored, others might nee consideration. As this PR touches 181 files, I will not do another thorough review.
3. PLEASE FIX WHAT YOU WANT TO FIX IN A SEPARATE COMMIT. DO NOT SQUASH COMMITS BEFORE RE-REVIEW; IT'S TOO HARD TRACK. - DM me when you've considered my comments/made any changes. This PR could probably be merged as is with little issue, but there's some stuff that I'm asking you to check before we merge it (mostly short description matching between versions).
- Beyond the scope of this PR: Much of this work was done in February. I wouldn't consider a lot of the short descriptions here "acceptable"; e.g., "If a cluster creation action fails, you might receive an error messages." doesn't do a lot for the user. This was probably done before we established a lot of standards for short descriptions, but I'm just calling it out. It's not your problem to fix, but I'd be remiss not mentioning it for any other reader.
- In c5c95f2, you have made slight changes to the modules/about-insights-advisor-workload-recommendations.adoc file. Those changes are not found here, nor are they found locally. The changes need made in this PR since we're backporting to 4.20.
- In https://github.com/openshift/openshift-docs/pull/106162/changes#diff-f032968b6c8cec97c38db08977922da2df3f9153a553b08530692ee0fd392bc8R27-R32, there is a module that was remade from "Accessing a Windows node", here: https://github.com/openshift/openshift-docs/pull/106162/changes#diff-7a3103b9c463936805bba599996648b53a7531d618438981cd56396e2e0aa088R10. That content (line 10) removed in this PR and I can't find it.
- modules/disabling-insights-advisor-recommendations.adoc needs the [role="_abstract"] label
- modules/displaying-potential-issues-with-your-cluster.adoc needs the abstract label.
|
Thanks for the review on this XXL, @stevsmit. Thanks for picking up a few minor issues that I have corrected and some needs discussion. I was overwhelmed while working on so many files and considering so many changes from the last PR and the current 4.21+ files. TBH, working with this PR was very challenging for me as it has so many files to work on and comparing the changes for all the files with the current 4.21+ docs and getting it right. Firstly, I started with matching the changes of 4.20 files that were missed by this #106162 PR, but then I noticed there were several changes that had been made to some of the files from Feb 2026 files. Some of the changes were not intended for 4.20, which I had to remove, even the newly added files. If you have seen some of the modules removed from assemblies that are present in 4.21+ docs, those would be the ones that are not for 4.20. Now, for the short descriptions, if I were to add abstracts as they are currently in 4.21+ docs, then the abstracts would definitely not be DITA compliant. As you mentioned in one of the comments, there are several standards that have been set for abstracts now. What I have tried to do here is correct those in as simple words as possible and not to change too much content. For example, many abstracts have referential words, which I have replaced with a generic line about the topic. I believe that is what @kalexand-rh and I had discussed earlier: that these changes were required to make content DITA-compliant, and these might need to be carried forward to 4.21+ as well to have similar content in all branches. Even in current 4.21+ docs, the older abstracts are not DITA-compliant, and that is what I have tried to cover in these support book changes. If we do not want to proceed with this line of action, then, of course, I can just change it to the same abstracts as they are in this #106162 PR and how they are in current 4.21+ docs, but I'm not sure all would be fully DITA compliant. There are some modules like this as well - https://github.com/openshift/openshift-docs/pull/106162/changes#diff-bbd7ba6c5e3028ca4562c80f8af0a02cffa08f9e29e7a352c428789fa685a330R10. - that is changed a lot in current 4.21+ doc and which I checed and replicated as it is in current doc. |
483cbbf to
1531851
Compare
97b835d to
e59484f
Compare
|
/retest |
|
@rh-sgehlot: all tests passed! Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
4 participants
Version(s):
4.20
Issue:
https://redhat.atlassian.net/browse/OSDOCS-18748
Link to docs preview:
QE review:
Additional information: